home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / sgeesx.z / sgeesx
Text File  |  1996-03-14  |  9KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SGEESX - compute for an N-by-N real nonsymmetric matrix A, the
  10.      eigenvalues, the real Schur form T, and, optionally, the matrix of Schur
  11.      vectors Z
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE SGEESX( JOBVS, SORT, SELECT, SENSE, N, A, LDA, SDIM, WR, WI,
  15.                         VS, LDVS, RCONDE, RCONDV, WORK, LWORK, IWORK, LIWORK,
  16.                         BWORK, INFO )
  17.  
  18.          CHARACTER      JOBVS, SENSE, SORT
  19.  
  20.          INTEGER        INFO, LDA, LDVS, LIWORK, LWORK, N, SDIM
  21.  
  22.          REAL           RCONDE, RCONDV
  23.  
  24.          LOGICAL        BWORK( * )
  25.  
  26.          INTEGER        IWORK( * )
  27.  
  28.          REAL           A( LDA, * ), VS( LDVS, * ), WI( * ), WORK( * ), WR( *
  29.                         )
  30.  
  31.          LOGICAL        SELECT
  32.  
  33.          EXTERNAL       SELECT
  34.  
  35. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  36.      SGEESX computes for an N-by-N real nonsymmetric matrix A, the
  37.      eigenvalues, the real Schur form T, and, optionally, the matrix of Schur
  38.      vectors Z.  This gives the Schur factorization A = Z*T*(Z**T).
  39.  
  40.      Optionally, it also orders the eigenvalues on the diagonal of the real
  41.      Schur form so that selected eigenvalues are at the top left; computes a
  42.      reciprocal condition number for the average of the selected eigenvalues
  43.      (RCONDE); and computes a reciprocal condition number for the right
  44.      invariant subspace corresponding to the selected eigenvalues (RCONDV).
  45.      The leading columns of Z form an orthonormal basis for this invariant
  46.      subspace.
  47.  
  48.      For further explanation of the reciprocal condition numbers RCONDE and
  49.      RCONDV, see Section 4.10 of the LAPACK Users' Guide (where these
  50.      quantities are called s and sep respectively).
  51.  
  52.      A real matrix is in real Schur form if it is upper quasi-triangular with
  53.      1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be standardized in the form
  54.                [  a  b  ]
  55.                [  c  a  ]
  56.  
  57.      where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc).
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  71.  
  72.  
  73.  
  74. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  75.      JOBVS   (input) CHARACTER*1
  76.              = 'N': Schur vectors are not computed;
  77.              = 'V': Schur vectors are computed.
  78.  
  79.      SORT    (input) CHARACTER*1
  80.              Specifies whether or not to order the eigenvalues on the diagonal
  81.              of the Schur form.  = 'N': Eigenvalues are not ordered;
  82.              = 'S': Eigenvalues are ordered (see SELECT).
  83.  
  84.      SELECT  (input) LOGICAL FUNCTION of two REAL arguments
  85.              SELECT must be declared EXTERNAL in the calling subroutine.  If
  86.              SORT = 'S', SELECT is used to select eigenvalues to sort to the
  87.              top left of the Schur form.  If SORT = 'N', SELECT is not
  88.              referenced.  An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if
  89.              SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex
  90.              conjugate pair of eigenvalues is selected, then both are.  Note
  91.              that a selected complex eigenvalue may no longer satisfy
  92.              SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may
  93.              change the value of complex eigenvalues (especially if the
  94.              eigenvalue is ill-conditioned); in this case INFO may be set to
  95.              N+3 (see INFO below).
  96.  
  97.      SENSE   (input) CHARACTER*1
  98.              Determines which reciprocal condition numbers are computed.  =
  99.              'N': None are computed;
  100.              = 'E': Computed for average of selected eigenvalues only;
  101.              = 'V': Computed for selected right invariant subspace only;
  102.              = 'B': Computed for both.  If SENSE = 'E', 'V' or 'B', SORT must
  103.              equal 'S'.
  104.  
  105.      N       (input) INTEGER
  106.              The order of the matrix A. N >= 0.
  107.  
  108.      A       (input/output) REAL array, dimension (LDA, N)
  109.              On entry, the N-by-N matrix A.  On exit, A is overwritten by its
  110.              real Schur form T.
  111.  
  112.      LDA     (input) INTEGER
  113.              The leading dimension of the array A.  LDA >= max(1,N).
  114.  
  115.      SDIM    (output) INTEGER
  116.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  117.              eigenvalues (after sorting) for which SELECT is true. (Complex
  118.              conjugate pairs for which SELECT is true for either eigenvalue
  119.              count as 2.)
  120.  
  121.      WR      (output) REAL array, dimension (N)
  122.              WI      (output) REAL array, dimension (N) WR and WI contain the
  123.              real and imaginary parts, respectively, of the computed
  124.              eigenvalues, in the same order that they appear on the diagonal
  125.              of the output Schur form T.  Complex conjugate pairs of
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  137.  
  138.  
  139.  
  140.              eigenvalues appear consecutively with the eigenvalue having the
  141.              positive imaginary part first.
  142.  
  143.      VS      (output) REAL array, dimension (LDVS,N)
  144.              If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur
  145.              vectors.  If JOBVS = 'N', VS is not referenced.
  146.  
  147.      LDVS    (input) INTEGER
  148.              The leading dimension of the array VS.  LDVS >= 1, and if JOBVS =
  149.              'V', LDVS >= N.
  150.  
  151.      RCONDE  (output) REAL
  152.              If SENSE = 'E' or 'B', RCONDE contains the reciprocal condition
  153.              number for the average of the selected eigenvalues.  Not
  154.              referenced if SENSE = 'N' or 'V'.
  155.  
  156.      RCONDV  (output) REAL
  157.              If SENSE = 'V' or 'B', RCONDV contains the reciprocal condition
  158.              number for the selected right invariant subspace.  Not referenced
  159.              if SENSE = 'N' or 'E'.
  160.  
  161.      WORK    (workspace/output) REAL array, dimension (LWORK)
  162.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  163.  
  164.      LWORK   (input) INTEGER
  165.              The dimension of the array WORK.  LWORK >= max(1,3*N).  Also, if
  166.              SENSE = 'E' or 'V' or 'B', LWORK >= N+2*SDIM*(N-SDIM), where SDIM
  167.              is the number of selected eigenvalues computed by this routine.
  168.              Note that N+2*SDIM*(N-SDIM) <= N+N*N/2.  For good performance,
  169.              LWORK must generally be larger.
  170.  
  171.      IWORK   (workspace) INTEGER array, dimension (LIWORK)
  172.              Not referenced if SENSE = 'N' or 'E'.
  173.  
  174.      LIWORK  (input) INTEGER
  175.              The dimension of the array IWORK.  LIWORK >= 1; if SENSE = 'V' or
  176.              'B', LIWORK >= SDIM*(N-SDIM).
  177.  
  178.      BWORK   (workspace) LOGICAL array, dimension (N)
  179.              Not referenced if SORT = 'N'.
  180.  
  181.      INFO    (output) INTEGER
  182.              = 0: successful exit
  183.              < 0: if INFO = -i, the i-th argument had an illegal value.
  184.              > 0: if INFO = i, and i is
  185.              <= N: the QR algorithm failed to compute all the
  186.              eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain
  187.              those eigenvalues which have converged; if JOBVS = 'V', VS
  188.              contains the transformation which reduces A to its partially
  189.              converged Schur form.  = N+1: the eigenvalues could not be
  190.              reordered because some eigenvalues were too close to separate
  191.              (the problem is very ill-conditioned); = N+2: after reordering,
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          SSSSGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  203.  
  204.  
  205.  
  206.              roundoff changed values of some complex eigenvalues so that
  207.              leading eigenvalues in the Schur form no longer satisfy
  208.              SELECT=.TRUE.  This could also be caused by underflow due to
  209.              scaling.
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.